3D Graphics Programming with QuickDraw 3D 1.5.4

Creating a Storage Object

Creating a storage object essentially involves indicating to QuickDraw 3D the location and possibly also the size of the piece of physical storage you later want to read data from or write data to. Once you've created a storage object, you attach it to a file object and perform all I/O operations using file object functions. Listing 4 illustrates how to create a storage object connected to an open Macintosh file.

Listing 4 Creating a Macintosh storage object



 
myErr = FSpOpenDF(&myFSSpec, fsCurPerm, &myFRefNum);

if (!myErr) 

    myStorageObj = Q3MacintoshStorage_New(myFRefNum);

Listing 5 illustrates how to open a file and create a UNIX storage object connected to that open file.

Listing 5 Creating a UNIX storage object



 
myFile = fopen("..:teacup.eb", "r");

if (myFile)

    myStorageObj = Q3UnixStorage_New(myFile);

Listing 6 illustrates how to allocate a block of memory and create a storage object connected to that block.

Listing 6 Creating a memory storage object



 
#define kBufferSize                         256



myBuffer = malloc(kBufferSize);

if (myBuffer)

    myStorageObj = Q3MemoryStorage_NewBuffer(myBuffer, 0, kBufferSize);

In the code shown in Listing 4 through Listing 6 , your application specifically reserves the desired piece of the physical storage device, either by opening a file or by allocating memory. In these cases, your application must also make sure to close the file or deallocate the memory block after you've closed or disposed of the associated storage object.

Note, however, that QuickDraw 3D provides two types of memory storage functions. The function Q3MemoryStorage_NewBuffer creates a new memory storage object using a specified buffer. The function Q3MemoryStorage_New creates a new memory storage object but copies the data in the specified buffer into its own internal memory. If you create a storage object by calling Q3MemoryStorage_New , you can dispose of the buffer once Q3MemoryStorage_New returns.

Whenever you create a storage object associated with an open file or an allocated memory block, you must close the file or dispose of the memory yourself.

When you open a piece of storage (that is, a file or a block of memory), you must not access that piece of storage once you've created a storage object to represent it. QuickDraw 3D assumes that it has exclusive access to all data in any part of a physical storage device associated with an open storage object.